Structures, Event Loop
Volume Number: 2
Issue Number: 6
Column Tag: The ABC's of C
Structures And The Event Loop 
By Bob Gordon, Apropos Publications, Minneapolis, MN
Beginning this month, we will start following the chapters in the Using the
Macintosh Toolbox with C book. This means we're will be learning about C and the
Macintosh at the same time. While this is probably not the optimum way to learn a
language, it means we can explore features of the language and the Mac and have a lot of
time to play around and make mistakes. As you will see from this month's effort, I am
not afraid to make lots of mistakes.
We are going to start right away with a program that demonstrates a bit about
the Event Manager. Events are a critical component to the way Macintosh software
functions. They are not visible like windows or pull-down menus, but they occupy a
central location in most applications nonetheless.
From the point of view of the Event Manager, Macintosh program spend most of
their time sitting around waiting for events. Events can come from the keyboard, the
mouse, disk drives, the Window Manager, et cetera, as well as your application.
For the moment, we won't worry too much about how the Event Manager gives
you an event. Instead, we'll use the event to examine an important C data construct
called a structure. A structure is a collection of variables usually of different types
organized under a single name (loosely paraphrased from K&R). An event from a
software point of view is a structure:
struct ER
{short what; /* kind of event */
long message; /* event info */
long when; /* time of event */
Point where; /* mouse location */
short modifiers; /* other info */
};
The variables collected together in the structure are members.
A structure declaration (as we have above) does not reserve any memory. We
still need to define a variable:
struct ER event;
defines the variable, event, to be of type ER. Now, when the Event Manager gives
us an event, we can examine its members to determine what to do. To access the
members of a structure, use a period between the variable name and the member name:
event.what
At this point, let us look more closely at the where member. It is obviously not
one of the standard C types. It is in fact another structure:
struct pt
{short v; /* vertical location */
short h; /* horizontal location */
};
So structures may be nested in other structures (you can also have arrays of
structures).
You noticed that I defined the structure "pt" not "Point." When we defined the
event variable, above, we wrote struct ER event. C requires that you let it know each
time you are dealing with a structure. Writing struct all over your programs can be a
drag as well as making them less readable. C has a couple of ways to deal with this
problem. One is the typedef, which is way of providing a new name for a type. Point
then becomes:
typdef struct pt Point;
The other technique is to use the preprocessor define feature:
#define EventRecord struct ER
Both of these techniques will increase the clarity of our code. The typedef is
preferred because it is actually a part of the compiler and can deal with certain
situations that can confuse the lexical substitutions of the preprocessor. Some micro C
compilers do not include typedefs, however.
Now that we have defined the EventRecord, we can get an event from the Event
Manager and see what to do with it.
Switch Statement
The first thing to do is decide what kind of event it is (from the what member),
and then take appropriate action. The clearest way to do this in C is with the switch or
case statement (C calls it switch, but many C programmers call it a case statement).
The switch is a multi-way branch:
switch (integer expression)
{
case constant1 : code;
break;
case constant2 : more code;
break;
default : code;
break;
}
The break statements are needed to keep the code from falling through the cases.
Without the break, if the expression matched constant2, it would continue execution
with the default code. The break forces execution to continue after the closing }. The
default is chosen if none of the other cases match. By the way, you can have several
constants that match one section of code. Each is preceded by case and followed by a
colon. In effect, they fall through to the first code to execute.
A Program that Demonstrates the Event Manager
/* Event Manager Demonstrator */
#include "stdio.h
#include "MacCDefs.h
#include "Events.h
main() /* This may look silly, but in */
{ /* subsequent programs we will have */
/* initialization routines up here. */
mainloop();
}
mainloop()
{
EventRecord event;
while (True)
{
if (GetNextEvent(everyEvent,& event))
switch ( event.what)
{
case mouseDown: printf("\nmouse down");
break;
case mouseUp: printf("\nmouse up");
break;
case keyDown: printf("\nkey down");
break;
case keyUp: printf("\nkey up");
break;
case autoKey: printf("\nautokey");
return;
break;
case updateEvt: break;
case diskEvt: printf("\ndisk event");
break;
case activateEvt: break;
case networkEvt: break;
case driverEvt : break;
case nullEvent: break;
}
}
}
GetNextEvent() is the Event Manager routine that returns the next event record
each time its called. If there are no events to return, it returns the Null Event.
All the constants (nullEvent, mouseUp, et cetera) and the EventRecord structure
are defined in Events.h. I recommend you take a look at the copy that comes with your
compiler.
The program exits on an autokey event. To stop the program, simply hold a key
down.
The first parameter to GetNextEvent() is the event mask. With it, you can select
the events to which you wish to respond. It's a bit mapped mask; you can combine
events by adding the constants defined in events.h together. EveryEvent is all 1 bits
(-1 decimal).
You will probably not see the key up event. It is generated when you release a
key. It took me awhile to find out why I wasn't seeing it, but I finally took a look at
Inside Macintosh.
There is a second event mask that controls which events get entered into the
event queue. Since GetNextEvent() gets events from the queue, if an event is masked
out, GetNextEvent() will never be able to return it. This event mask is initialized to:
everyEvent - keyUpMask
so it will not even post key up events. There is a function, SetEventMask(), that
will set this, but it is apparently not included in Mac C.
Some Things to do
This program is very brief, but you can easily add a few lines to get a better feel
of how the Event Manager works and how to use some C functions. Try examining the
where field on each event. Remember this is a Point structure. The message and
modifier fields provide essential information for some events, e specially key events.
Print these out as well.
There are a number of other functions in the Event Manager. They allow reading
the mouse, keyboard, and time without waiting for an event. There is also a function to
read the event queue that leaves the event in the queue.
We will not do any more with the Event Manager at this time, but we will use it
in probably every program we write.
Finally, if anyone is reading along, I would appreciate hearing from you. Let me
know if this is useful or if you have an idea for a short program we can do in the
column.